CwbCoPwr

Version 1.01

This tool allows you to set various advanced IBM i Access client communications settings
not configurable through other IBM i Access applications.

The program, CwbCoPwr.exe, has not been thoroughly tested under all conditions. IBM, therefore, does not guarantee or imply its reliability, serviceability, or function.

THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGMENT ARE EXPRESSLY DISCLAIMED. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSIONS MAY NOT APPLY TO YOU. IN NO EVENT WILL IBM BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, SPECIAL OR OTHER CONSEQUENTIAL DAMAGES FOR ANY USE OF THE PROGRAM INCLUDING, WITHOUT LIMITATION, ANY LOST PROFITS, BUSINESS INTERRUPTION, LOSS OF PROGRAMS OR OTHER DATA ON YOUR INFORMATION HANDLING SYSTEM OR OTHERWISE, EVEN IF WE ARE EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Usage Syntax:

Each of the three below sections of settings are mutually exclusive. Only one of the below can be used for each invocation of the utility.

Help Options:
CWBCOPWR                       - Command summary
        [/HELP]                - Command summary
        [/HELPDETAILS]         - Extensive help information in html format

Machine Keepalive Settings:
CWBCOPWR /MKA:<freq.>,<start> - Machine KA, seconds: between, till start
[/DFLT] - Sets your machine KA values to default (1,7200)

Service Performance Settings:
CWBCOPWR /CLR                  - Remove ALL previously set performance overrides at ALL levels
CWBCOPWR /SVC:<svc>,<svc>,..   - The service(s) to affect ("ALL" affects all)
            [/SYS:<system>]        - system (in active environment) to be affected by the changes
            [/RMV]                 - Reset all options back to defaults for this service
            [/SETTO:<service>]     - Sets /SVC services equivelent to <svc>
            [/SC:<cache>,<thresh>] - CAE Send cache,threshold
            [/SMX:<max size>]      - CAE Single max send amount
            [/KA:(1-ON or 0-OFF)] - TCP/IP KeepAlives 1-ON 0-OFF
            [/NGL:(1 or 0)]        - TCP/IP Nagling 1-ON 0-OFF
            [/WSS:<buffer size>]   - TCP/IP send buffer
            [/WSR:<buffer size>]   - TCP/IP receive buffer
            [/RT:<timeout period>] - TCP/IP receive timout period
            [/ST:<timeout period>] - TCP/IP send timeout period

Possible names for configurable services (name or number may be used for /SVC):
       1        central                   2        file
       3        netprt                    4        database
       5        odbc                      6        dataqueue
       7        rmtcmd                    8        signon
       9        ddm                       10       mapi
       11       usf                       12       web-admin*
       13       telnet*                   14       mgmtctrl
       15       sts                       16       opconsole
       17       vcons

* Changes made to these services will have no effect as they do not use settings set by this program.
NOTE: Not all services are applicable to all operating systems and releases.

"Mileage may vary" - Changing any of these values listed below may result in better or worse network performance depending upon your machine, OS, network connection and other variables.
Help Options, Machine Keepalive Settings, and Service Performance Settings are all mutually exclusive options for calling this utility. One cannot display the help and change a performance setting in the same invocation.
More information and help with things relating to this utility, see the usage help section at the end of this document.

back to top

`/MKA:<frequency>,<start>`

Keepalives are a TCP/IP option used to keep a connection to a server open that might possibly time out after a long period of inactivity. Keepalives generally start after a given amount of inactivity, then regularly ping the server to keep the current connection open.

The /MKA option sets the TCP/IP values for keepalives over the entire machine. Machine keepalive values are keepalive settings that, once set, affect all TCP/IP connections that have keepalives turned on. The two settable values are frequency and start. Frequency is the number of seconds between the sends of keepalives. Start is the number of seconds of inactivity on a connection before keepalives will start to be sent.

You can use the /DFLT paramater following /MKA to reset the keepalive settings for the machine back to their default values: Frequency, 1 second. Start after 7200 seconds of inactivity.

Usage Examples:

/MKA                   - outputs the current machine keepalive settings
/MKA /DFLT             - resets machine keepalive settings back to defaults
                           Frequency = 1 second, Time till start = 7200 seconds
/MKA:<freq.>,<start>   - set the frequency and start values

back to top

`/SVC:<service>,<service>.....`

The /SVC tag is used to specify which services are to be affected by the tags that follow. You can list several services that you wish your updates to affect, they must all be listed following the /SVC tag separated by a comma. The list of services must not contain any blanks. Use of the /SVC parameter with no options will output the current settings for all services.

When setting parameters with the /SVC tag, the values set will be set at the service level. Service level settings affect all systems across all environments unless the setting is overridden at the system level (see /SYS). For any service that the defaults have not been overridden, the settings are considered to be at the default level. When a communication connection is made, iSerise Access will first look for any overide settings at the system level in the active environment. If no overrides were found there, IBM i Access proceeds to look to the service level settings. Lastly, if no overrides were found, the default settings are used.

Example output from the /SVC and /SYS option:

'O' Performance Setting Override Level: ' '=Default 'S'=System 'G'=Global
'N' Nagling 1=ON 0=OFF
'K' KeepAlives
'*' denotes a value you just changed.
'-' denotes a Winsock default will be used.

Current Configuration: Global Settings
===============================================================================
   Service     ONK SndCache SndThold SndMax WSSndBuf WSRcvBuf WSSndT WSRcvT
-------------+-----+--------+--------+--------+--------+--------+------+------+
1 central   | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
2 file      | 00 |   8192 |   8192 | NoMax |      0 |      - |    - |    - |
3 netprt    | 00 | 16384 | 16384 | NoMax |      0 |      - |    - |    - |
4 database | 00 | 16384 | 16384 | NoMax |      0 |      - |    - |    - |
5 odbc      | 00 |   8192 |   8192 | NoMax |      0 |      - |    - |    - |
6 dataqueue | 00 |   8192 |   8192 | NoMax |      0 |      - |    - |    - |
7 rmtcmd    | 00 |   8192 |   8192 | NoMax |      0 |      - |    - |    - |
8 signon    | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
9 ddm       | 00 |   8192 |   8192 | NoMax |      0 |      - |    - |    - |
10 mapi      | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
11 usf       | 00 |   8192 |   8192 | NoMax |      0 |      - |    - |    - |
12 web-admin | 00 |   8192 |   8192 | NoMax |      0 |      - |    - |    - |
13 telnet    | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
14 mgmtctrl | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
15 sts       | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
16 opconsole | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
17 vcons     | 00 |      0 |      0 | NoMax |      - |      - |    - |    - |
===============================================================================
NOTE: See the help file for the current IBM i Access default settings

Usage Examples:

/SVC - outputs the current settings for all services at the service level
/SVC:<service>... [options] - set options for services listed

back to top
/SYS:<system>

This option allows overriding values for a particular system. The system specified must exist in the active environment. If you wish to make changes to a system that is not currently in the active environment, you must enter Operations Navigator and set your active environment to the one containing the desired system. Any setting set at the system level will override any service level or default level settings. Any services that have not been overridden at the system level will use service level settings if set, otherwise the defaults are used. The sample output above shows two overrides at the system level (services 7 and 8) and several overrides at the service level (services 1, 2, and 3) and the rest of the services using the default options.

Usage Examples:

/SVC /SYS:<system> - outputs the current settings for all services at the system level
/SVC /SYS:<system> [options] - sets the options specified at the system level for the services listed

back to top

`/RMV`

This option will remove all the overrides previously set for all the specified services/system, essentially resetting those values back to defaults. /RMV overrides any other tags that may be listed following the /SVC or /SYS tags. Using these defaults will always be safe for the service you are using. If any changes you have made to these services settings result in poor communcations performance, the defaults will restore "normal" IBM i Access communications behavior.

Usage Examples:

/SVC:14 /RMV - will set service 14 (mgmtctrl) settings back to generic defaults

back to top

`/SETTO:<Service>`

The /SETTO tag can be used to set preferences of any services/system specified to be exactly the same as the service specified by the /SETTO tag. The single argument for this tag must be the integer representation for the service to be copied (1 - 14). Any other tag following /SVC and /SYS will be ignored when using the /SETTO tag except /RMV, which will override use of /SETTO.

Usage Examples:

/SVC:2,ddm /SETTO:1 - sets preferences for services 2 (file) and 9 (ddm) equal to those set for service 1 (central)

back to top

`/KA: [ 1 | 0 ] where 1 = ON and 0 = OFF`

Use this option to turn TCP/IP Keepalives on or off for the services/system specified. If Keepalives are on, they will use the values set at the machine level for sending keepalives. Those settings can be tweaked via the /MKA parameter.

The /KA tag takes a single number for an argument. This number must be a 1 or 0: 1 = ON, 0 = OFF. Lack of any parameters will result in resetting usage of keepalives back to the default usage value, OFF.

Turning keepalives on will cause keepalives to be sent in the PC to the server direction holding the connection open and allowing for earlier detection of some network problems that may occur.

Usage Examples:

/SVC:1 /KA - resets keepalive usage for service 1 (central) to default, OFF
/SVC:1 /KA:1 - turns usage of keeplives ON for service 1 (central)

back to top

`/SC:<Send Cache Size>,<Send Threshold Size>`

The send cache is the size, in bytes, of the IBM i Access send buffer that data to be sent is copied into to await a trigger condition which will cause the buffer to be flushed. The send threshold is the size, in bytes, of part of the IBM i Access send buffer that must be filled before a flush of the buffer will occur. This must be no greater than the send buffer size, but may be smaller.

/SC is used to set the IBM i Access send cache and send threshold sizes for the services/system specified. An acceptable value for this parameter is a single number greater than or equal to 0, or two numbers greater than or equal to 0 seperated by a comma. These values are the size in bytes of the IBM i Access send cache and send threshold respectively. Lack of any parameters on the /SC tag will result in a reset to the default set by this application, 8192 bytes for send cache and 8192 bytes for the send threshold, an optimal size for most services. When 0 is specified for the send cache, the IBM i Access send buffer will not be used. When only a single number is used, it will set both the send cache and the send threshold to that value. If both numbers are used, the first value is for he send cache, the second for send threshold.

Depending on the app being used, a change in the buffer and threshold sizes may increase or decrease performance. Instances where an app ocasionally sends large packets of data, it may be advantageous to increase the buffer size for the large packets, but maintain a lower threshold size for most data.

Usage Examples:

/SVC:Signon /SC             - sets the send cache and threshold values for service 8 (signon) to default, 8192 bytes, 8192 bytes
/SVC:Signon /SC:16384,8192 - sets the send cache for service 8 (signon) to 16384 bytes, and send threshold to 8192 bytes
/SVC:Signon /SC:8192        - sets the send cache and send threshold for service 8 (signon) to 8192 bytes
/SVC:Signon /SC:0           - turns off the Clint Access send buffering for service 8 (signon)

back to top

`/SMX:<MAX Size>`

The max size, in bytes, is the maximum amount of data that IBM i Access will send at one time. If a user program wants to send more then the max size, IBM i Access will break up the data into max size chunks and send one at a time.

The main reason for this value is for extra large sends (greater than ~10MB). Some MS TCP/IP stacks do not handle this situation very well and will report an "10055 No More Resources" on the send call. So, if your PC has limited memory and your constantly over-committing memory, this value will help smooth resource usage out.

Usage Examples:

/SVC:Signon /SMX - sets the send max size to a very large number (2Gig-1) so that all data is sent with one send call
/SVC:ODBC /SMX:65536 - sets the send max size to 64K. This will break any large sends and workaround MS TCP/IP bugs

back to top

`/NGL: [ 1 | 0 ] where 1 = ON and 0 = OFF`

The TCP/IP software itself can provide send buffering, using a technique called the Nagle Algorithm. When you turn "nagling" on, TCP/IP will perform this buffering with the Winsock send buffer, whether or not Client Access performs send buffering.

The /NGL parameter takes a single numeric value for a parameter. This number must be a 1 or a 0: 1 = ON, 0 = OFF. Lack of any parameters will result in resetting usage of nagling back to the default, OFF.

The Nagle Algorithm is used to send full frames of data over the wire which can be advantageous with certain types of network connections. Use of this algorithm may be desirable when connected by modem and/or in a Wide-Area Network (WAN) environment, but has been found to cause poor performance in some Local Area Network (LAN) environments.

Usage Examples:

/SVC:2 /NGL - resets nagling for service 2 (file) back to default, OFF
/SVC:2 /NGL:1 - turns nagling ON for service 2 (file)

back to top

`/WSS:<Winsock Send Buffer Size>`

The TCP/IP Winsock send buffer may be used in place of the IBM i Access send buffer if the IBM i Access send cache value is set to 0 or if nagling is turned on.

/WSS sets the Winsock send buffer size for the specified services/system. This tag takes one numeric value for a parameter, the size in bytes of the Winsock send buffer. Lack of any parameters or a numeric value of -1 will cause no override and the Winsock send buffer size will be used. The default value for the Winsock buffer may vary amongst different platforms.

Usage Examples:

/SVC:central /WSS - resets size of the Winsock send buffer back to the Winsock default for service 1 (central)
/SVC:central /WSS:8192 - sets the Winsock send buffer size to 8192 bytes for service 1 (central)

back to top

`/WSR:<Winsock Receive Buffer Size>`

The TCP/IP Winsock receive buffer is the size, in bytes, that Winsock allocates for incoming data to be stored until retrieved by the application.

/WSR sets the Winsock receive buffer value for the specified services/system. This tag takes one numeric value for a parameter, the size in bytes of the Winsock receive buffer. Lack of any parameters or a numeric value of -1 will cause no override and the Winsock receive buffer size will be used. The default value for the Winsock buffer may vary amongst different platforms.

Usage Examples:

/SVC:4 /WSR - resets size of the Winsock receive buffer back to the Winsock defaults for service 4 (database)
/SVC:4 /WSR:4096 - sets the Winsock receive buffer size to 4096 bytes for service 4 (database)

back to top

`/RT:<Receive Timeout Period> or /ST:<Send Timeout Period>`

When a program expects data to be sent to it, it calls recv() to receive the data. If the program on the other end fails to send the data, or the data gets lost somehow, the recv() call will never return. In this case, the program expecting to receive the data will appear to be "hung". To avoid this hang condition, a receive timeout period can be set. If winsock does not receive the expected within the timeout period, it will return an error to the receiving program, which will then fail appropriately rather than hang.

/RT sets the TCP/IP Winsock receive timeout for the specified services/system. This tag takes one numeric value for a parameter, the number of seconds to wait before a recv call should timeout and the program fail. Lack of any parameters or a numeric value of 0 will cause the recv calls to never
timeout. The default value for the Winsock receive timout period may vary amongst different platforms.

/ST sets the TCP/IP Winsock send timeout for the specified services/system. This tag takes one numeric value for a parameter, the number of seconds to wait before a send call should timeout and the program fail. Lack of any parameters or a numeric value of 0 will cause the send calls to never timeout.

Usage Examples:

/SVC:7,8 /RT - turns off any previously set receive timeout for services 7 (rmtcmd) and 8 (signon)
/SVC:7,8 /RT:30 - sets the receive timeout to 30 seconds for services 7 (rmtcmd) and 8 (signon)

back to top
/CLR

The /CLR tag will force a reset to the default settings for all systems and server overrides that have been set on the machine. All overrides that can be set by via the /SVC tag will be removed. These overrides include settings for all systems at the system level for the active environment, for all systems level of all non-active environments, and also the server level overrides.

Use of this tag is advised only if you are having trouble with any performance parameters you have set and you wish to clear all set overrides. If you have any override settings you may wish to keep, you must either reset them after use of this parameter, or clear individual overrides by hand by using the /RMV tag.

Usage Example:

/CLR - removes all set overrides on the system

back to top

`Additional Information`

For any of the above communications settings, if you want to ensure that your setting changes have taken effect, you can look at a detailed trace. Both the CAE and TCP/IP communication setting values are listed there.
See the IBM i Access web site for more information or to give feedback on this tool.